<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>newgrp</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_1498">&nbsp;</a>NAME</h4><blockquote>
newgrp - change to a new group
</blockquote><h4><a name = "tag_001_014_1499">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

newgrp <b>[</b>-l<b>][</b><i>group</i>

newgrp <b>[</b>-<b>][</b><i>group</i><b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_1500">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>newgrp</i>
utility creates a new
shell execution environment
with a new real and effective group identification.
Of the attributes listed in
<xref href=shexenv><a href="chap2.html#tag_001_012">
Shell Execution Environment
</a></xref>,
the new shell execution environment will retain
the working directory, file creation mask
and exported variables from the previous environment
(that is, open files, traps, unexported variables,
alias definitions, shell functions and
<i>set</i>
options may be lost).
All other aspects of the process environment that are preserved by the
<i>exec</i>
family of functions in the <b>XSH</b> specification
also are preserved by
<i>newgrp</i>;
whether other aspects are preserved is unspecified.
<p>
A failure to assign the new group identifications (for example, for security
or password-related reasons) does not prevent the new shell execution
environment from being created.
<p>
The
<i>newgrp</i>
utility affects the supplemental groups for the process as follows:
<ul>
<p>
<li>
On systems where the effective group ID is normally in the supplementary
group list (or whenever the old effective group ID actually is in the
supplementary group list):
<ul>
<p>
<li>
If the new effective group ID is also in the supplementary group list,
<i>newgrp</i>
will change the effective group ID.
<p>
<li>
If the new effective group ID is not in the supplementary group list,
<i>newgrp</i>
will add the new effective group ID to the list, if there is room to add it.
<p>
</ul>
<p>
<li>
On systems where the effective group ID is not normally in the supplementary
group list (or whenever the old effective group ID is not in the
supplementary group list):
<ul>
<p>
<li>
If the new effective group ID is in the supplementary group list,
<i>newgrp</i>
will delete it.
<p>
<li>
If the old effective group ID is not in the supplementary list,
<i>newgrp</i>
will add it if there is room.
<p>
</ul>
<p>
</ul>
<dl><dt><b>Note:</b>
<dd>The <b>XSH</b> specification does not specify whether the effective group ID of a process is
included in its supplementary group list.
</dl>
With no operands,
<i>newgrp</i>
will change the effective group back to
the groups identified in the user's user entry, and
will set the list of supplementary groups to that set
in the user's group database entries.
<p>
If a password is required for the specified group, and the
user is not listed as a member of that group
in the group database, the user will
be prompted to
enter the correct password for that group.
If the user is
listed as a member of that group, no password will be requested.
If no password is required for the specified group,
it is implementation-dependent whether
users not listed as members of that group can change to that group.
Whether or not a password is required, implementation-dependent
system accounting or security mechanisms may impose additional authorisation
restrictions that may cause
<i>newgrp</i>
to write a diagnostic message and suppress the changing of the group
identification.
<br>
</blockquote><h4><a name = "tag_001_014_1501">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>newgrp</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> , except
that the obsolescent version uses "-" in a non-standard manner.
<p>
The following option is supported:
<dl compact>

<dt><b>-l</b>
<dd>(The letter ell.)

<dt><b>-</b><dd>Change the environment to what would be expected if the
user actually logged in again.

</dl>
</blockquote><h4><a name = "tag_001_014_1502">&nbsp;</a>OPERANDS</h4><blockquote>
The following operand is supported:
<dl compact>

<dt><i>group</i><dd>A group name from the group database or a non-negative numeric group ID.
Specifies the group ID to which the real and effective group IDs
will be set.
If
<i>group</i>
is a non-negative numeric string and exists in the
group database as a group name (see
<i><a href="../xsh/getgrnam.html">getgrnam()</a></i>),
the numeric group ID associated with that group name will be used as
the group ID.

</dl>
</blockquote><h4><a name = "tag_001_014_1503">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_1504">&nbsp;</a>INPUT FILES</h4><blockquote>
The file
<b>/dev/tty</b>
is used to read a single line of text for password checking,
when one is required.
</blockquote><h4><a name = "tag_001_014_1505">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>newgrp</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_1506">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1507">&nbsp;</a>STDOUT</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_1508">&nbsp;</a>STDERR</h4><blockquote>
Used for diagnostic messages and
a prompt string for a password, if one is required.
Diagnostic messages may be written in cases where the exit status is not
available; see <b>EXIT STATUS</b>.
</blockquote><h4><a name = "tag_001_014_1509">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1510">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1511">&nbsp;</a>EXIT STATUS</h4><blockquote>
If
<i>newgrp</i>
succeeds in creating a new shell execution environment, whether or not the
group identification was changed successfully,
the exit status will be the exit status of the shell.
Otherwise, the following exit value is returned:
<dl compact>

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_1512">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
The invoking shell may terminate.
</blockquote><h4><a name = "tag_001_014_1513">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
There is no convenient way to enter a password into
the Group Database.
Use of group passwords is not encouraged,
because by their very nature they encourage poor security practices.
Group passwords may disappear in the future.
<p>
A common implementation of
<i>newgrp</i>
is that the current shell uses
<i>exec</i>
to overlay itself with
<i>newgrp</i>,
which in turn overlays
itself with a new shell after changing group.
On some systems, however, this may not occur and
<i>newgrp</i>
may be invoked as a subprocess.
<p>
The
<i>newgrp</i>
command
is intended only for use from an interactive terminal.
It does not offer a useful interface for the support of applications.
<p>
The exit status of
<i>newgrp</i>
is generally inapplicable.  If
<i>newgrp</i>
is used in a script, in most cases it will successfully invoke a new shell
and the rest of the original shell script will be bypassed when the new
shell exits.
Used interactively,
<i>newgrp</i>
displays diagnostic messages to indicate problems.
But usage such as:
<pre>
<code>
newgrp foo
echo $?
</code>
</pre>
is not useful because the new shell might not have access to any status
<i>newgrp</i>
may have generated (and most historical systems do not provide this status).
A zero status echoed here does not necessarily indicate that the user has
changed to the new group successfully.
Following
<i>newgrp</i>
with the
<i><a href="id.html">id</a></i>
command provides a portable means of determining
whether the group change was successful or not.
</blockquote><h4><a name = "tag_001_014_1514">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1515">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1516">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="sh.html">sh</a></i>,
the <b>XSH</b> specification description of
<i>exec</i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
